QuickTime 4 Reference

The Effect Component Interface

Effect components, as with all other types of QuickTime components, must implement a defined set of functions. To ease the component development process, the Generic Effect component is provided for you. This component implements many of the "housekeeping" functions that all components must perform. In most cases, these default implementations are appropriate for your effect, and you simply delegate these functions to the generic effect component. In the rare instances when you need to provide your own implementations of one of these basic functions, you can override the generic version and provide your own implementation.

By delegating many of the functions to the generic effect, you not only decrease the number of functions you must implement, you also produce a smaller effect component, because common code is stored only once, in the generic effect.

The framework code provided in the dimmer effect sample ( "Introduction to the Dimmer Effect" ), shows how to delegate interface functions to the generic effect component.

Your component must provide implementations for these functions:

Open: opens a connection between the client software and your component.
Close: closes the connection between the client and your component.
Version: returns the version number of your component.
EffectSetup: is called once before a sequence of frames are rendered. This gives your effect the chance to set up variables that will alter their value during the execution of a sequence of frames.
EffectBegin: is called once before a frame is rendered. Your component can safely perform operations that move memory when this function is called.
EffectRenderFrame: is called to render a frame. Because this function can be called asynchronously, it is not safe to perform operations that may move memory during this call.
EffectCancel: cancels the rendering of a frame. If your component supports asynchronous operation, this function can be called while a frame is being rendered.
GetParameterListHandle: returns a parameter description atom container, as described in the section "Supplying Parameter Description Information" .
GetCodecInfo: returns information to the codec manager about the capabilities of your component.
EffectGetSpeed: returns the approximate number of frames per second that your effect is capable of transforming.

These functions can be categorized into four groups. The Open andClose functions deal with maintaining a connection between your component and client software. In most cases, you can implementation these functions using the sample code provided by Apple without modification.

The Version , GetParameterListHandle , GetCodecInfo and EffectGetSpeed functions return information about your component. The most important of these functions is GetParameterListHandle , which returns a description of the parameters that your effect can take. See "Supplying Parameter Description Information" for more details of this what this function should do.

The EffectSetup function is called immediately before your component is required to render a sequence of frames. On entry, the function contains a description of the sequence that is about to be rendered. Most importantly, it describes the bit depth and pixel format of the sources that your component has to deal with. Your Setup function can then verify that your component can handle these formats. If it cannot, EffectSetup should return the "closest" bit depth and pixel format combination that it can handle, and QuickTime will generate versions of the sources and destination in the requested format. This ensures that your effect component is given source and destination buffers in a format that it understands. See "The EffectRenderFrame Function" for more details.

The most significant function group contains the EffectBegin , EffectRenderFrame, and EffectCancel functions. These functions contain the implementation of your effect algorithm. In most cases, you can implement the EffectCancel function simply by using the sample code provided by Apple. The implementation of the EffectBegin and RenderFrame functions is covered in "Implementing the EffectBegin and EffectRenderFrame Functions" .

Full details of the interface functions your component must supply are given in "Component-Defined Functions" .